xss

Section: Games and Demos (6)
Updated: November 1994
Index Return to Main Contents

NAME

xss - a scene setter for the X Window System, using polyh data

SYNTAX

xss [options] <polyh or xss file>

DESCRIPTION

Xss is an X11 program that displays and manipulates wireframe objects. It takes a .polyh or .xss file as input and optional switches as its command line arguments.

Options

All these options can be abbreviated to the least letters needed to make the chosen option distinct.

-display <display>: sets the X display name. By default it is the local host or that one defined in the environment variable DISPLAY.
-geometry <geometry>: sets the X geometry. (770x476 or 720x445)
-fontname <name>: uses the font described by the name. The default is the fixed font.

Once running, it will display a few parameters and some help messages in the terminal window and create a graphics window with a wireframe model of objects given by the input file.

CONCEPTS

In xss, the three Cartesian axes are taken to be aligned horizontal (x - positive to the right), vertical (y - positive upward) and normal (z - positive toward the viewer) to the viewer.

There are four modes in xss. Three object modes - rotation, scaling and translation - and a rotation axis mode.

In the object modes, the current object is drawn in solid lines whilst the other objects are drawn in dashed lines. The current object can be rotated, translated, magnified or shrunk using either the keys specified below or the control panel. Additional objects and scenes can be loaded in and objects can be cloned or deleted as well.

In the rotation axis mode, a line appears which can be oriented in any direction. The line shows the rotation axis that will be used in xpgs. It is made of two halves, each drawn differently. The solid half is the northern part of the axis, the dashed half is the southern part. The rotation is defined to be clockwise as you look along the axis from the south pole northward.

Once satisfied with the scene you have composed, the configuration can be saved as a .xss file for use in xpgs, cvtoppm and sisgen.

GRAPHICAL USER INTERFACE

Xss has a rather primitive user interface, partly because I haven't got round to learning to use Xt and some widget set.

WINDOW LAYOUT

There are two persistent windows in xss: the main graphics window and the control panel. The main window shows, on startup, four subwindows:

   -----------------------------------
   |                   |             |
   |  ----> x          |             |
   |  |                |             |
   |  |                |             |
   |  v                |             |
   |  z                |             |
   |-------------------|-------------|
   |  y                |          y  |
   |  ^                |          ^  |
   |  |                |          |  |
   |  |                |          |  |
   |  ----> x          |    z <----  |
   |                   |             |
   -----------------------------------

The top right subwindow contains some information about the program, the .xss file name and the current object. The other subwindows display the three orthographic views (third angle projections?) which are front, right end and plan.

The objects can be drawn as wireframe figures or bounding boxes, with or without clipping. The clipping in the orthographic scheme is separately done in each view at the x=0, y=0 or z=0 plane.

The projection scheme be changed to a perspective one. In this scheme, there is only one view and hence only one window (no subwindows). Also clipping is done at the z=0 plane.

Both persistent windows are sensitive to key presses - as long as the cursor (or mouse pointer) is within their boundaries. See below for the keys.

Using the mouse in the main window is limited to popping up the help window which contains a reminder of the keys and their functions.

The control panel is where the mouse actions are most useful. This panel is divided into two types of mouse sensitive regions: the buttons and the mouse pad.

DIALOGUE POPUPS

When any user text input is required - for instance when a file name to save to - a dialogue window pops up at the pointer location.

The popup window has three buttons which perform the following functions:

OK: returns the text.
Clear: clears all text from the input field.
Cancel: returns without any text and cancels the operation which prompted popup.

A number of keys are defined to facilitate editing (most a la emacs, hmm is that correct French?):

Left & Right cursor keys, ^B & ^F: moves the cursor along the text.
^A & ^E: moves the cursor to the beginning and end of the text.
Backspace, Delete & ^H: deletes the character to the immediate left of the cursor.
Enter, Linefeed & Keypad Enter: finishes and commits the input text.
Escape: cancels the input.
^D: deletes the character under the cursor.
^U: deletes all the text from the beginning of the line to just left of the cursor.
^C: clears the text field.

The pointer can also be used to move the text cursor: position the pointer to where you want the cursor to be then click one of the mouse buttons and release.

The dialogue popup also appears in vpgs and xpgs.

PANEL BUTTONS

All buttons in the control panel are of the press and release variety. If you press button one of the mouse (usually the left button) in the "Clip" box and release whilst the pointer is still in that box then the action corresponding to "Clip" is performed.

Most buttons are single action devices but others are toggles which indicate the state of the program.

Quit: quits the program.
Write Bitmap: writes an X11 bitmap of the main window.
Save xss: saves the whole scene as a .xss file.
Merge: inserts an old scene from another .xss file.
Load: loads another object, i.e. .polyh file.
Clone: replicates the current object.
Delete: removes the current object.
Other: moves to another object.
Initialise: re-initialises the current object.
Translate/Turn/Magnify/Axis: puts xss into the translate/turn/magnify/axis mode.
Clip: switches on the clipping.
Projection: changes the projection scheme.
B Box: toggles the visibility of the bounding box of the current object.
- Mag +: shrinks or magnifies the current object.

MOUSE PAD

This is the large box on the bottom of the control panel containing several small squares and some line drawings.

It has two appearances depending on the state of xss: a rotating state or a linear state. The rotating state is shown by a dashed sphere with three arrowed great circles and occurs when xss expects the action on the current object (or axis) to be a rotation. The linear state is depicted by a set of three arrowed mutually perpendicular axes and occurs when the anticipated action is a translation or scaling.

The line graphics are an isometric view of the sphere or the triad of axes with x and y directions going horizontally and vertically, respectively and the z direction, from positive to negative, goes from bottom left diagonally across to top right.

The square boxes within the mouse pad indicate the areas that are sensitive to mouse presses. Their positions in the mouse pad, in relation to the arrowed lines and curves, indicate the action to be taken when pressed. For example, in the rotating state, the rightmost square is configured to rotate the current object clockwise as it faces the viewer; in the linear state it is configured to translate the object right or magnify it horizontally.

The squares allow a click, hold, drag and release methodology (ugh). The further the pointer is released from the centre of the square it had click on, the more an action is performed - provided the pointer is released within the boundary of the mouse pad. As an aid, circles are drawn to help the user to gauge the magnitude of their action, they indicate the number of times a transformation will be performed.

MOUSE BUTTONS

The third (usually the right) mouse button acts like the first button but in actions where transformations are made, its effects are fivefold. The shift key can also be used in conjunction with the first mouse button to act like the third.

KEYS

With the mouse pointer within the boundaries of the graphics window, xss will respond to a set of keypresses.

q: quits the program.
h: pops up a help window.
w: saves the main window as an X11 bitmap.
s: saves the whole scene as a .xss file.
f: inserts an old scene from another .xss file.
r: replicates the current object.
l: loads another object, i.e. .polyh file.
d: deletes the current object.
o: moves to another object.
i: re-initialises the current object.
b: toggles the bounding box of the current object.
c: un/clips the current object at the z=0 plane, rendering the portion below z=0 invisible. This function is to aid depth perception.
p: change the projection scheme from three orthographic views to one perspective view, or vice versa.
m: magnifies the current object.
n: shrinks the current object.
t: toggles the between the turn, magnify and translate modes.
a: toggles the rotation axis definition mode.
v: toggles the verbosity of the program.
SHIFT (the shift keys): toggles the magnitude of the changes. Holding down the shift key makes all subsequent changes relatively coarse (by a factor of five) and releasing it reverts to finer changes.

The manipulation keys are the cursor keys, the greater-than (or full stop or period) key and the less-than (or comma) key. They change the objects in a visually obvious way.

In rotation mode, (+ means clockwise about positive axis)

x axis: - Up + Down

y axis: - Left + Right

z axis: + <, - >.

In translation mode,

x axis: - Left + Right

y axis: + Up - Down

z axis: + <, - >.

In the rotation axis definition mode, the manipulations keys perform similar tasks to the rotation mode.

BUILT-IN OBJECTS

A number of builtin objects are now available. To access them, press the "l" key or "Load" button and type in a name (with parameters) instead of a .polyh file.

The following primitives are available:

polygon(pdiv, pbeg, pend, chord): a polygon in the x-y plane, made from a regular polygon of pdiv sides (3) and starts at the vertex pbeg (0) and ends at vertex pend (pdiv). If chord (0) is 0 then the polygon is closed with lines from the ends to the centre, otherwise a line joins the ends directly.
pyramid(pdiv, pbeg, pend, chord): a pyramid with a polygon base described by polygon(pdiv, pbeg, pend, chord) and has an apex at (0,0,1).
prism(pdiv, pbeg, pend, chord, zdiv, zno, lid): a prism made from a polygon base that extends out in the positive z direction to z=1. This is divided into zdiv (1) subsections and the prism comprises zno (zdiv) of these. (If ano is greater than adiv, then the shape is further extended.) If lid (1) is 0 then the prism is not capped, otherwise it has end faces.
spiral(pdiv, pbeg, pend, chord, xs, yinc, adiv, ano, lid): a shape made from the extrusions of a polygon, shifted xs (2.0) in the x direction, rotated about the y axis. It is further shifted smoothly so that it is displayed by yinc (0.0) in the y direction every completed turn. This shell is divided into adiv (36) subsections and the spiral is composed out of ano (adiv) of these. (If ano is greater than adiv, then the shape is extruded further.) If lid (0) is 0 then the spiral is not capped, otherwise it has end faces.

The numbers in parentheses shown the default values taken by the program. When you use the primitives, you need not specify all the arguments, later values can be omitted (a la C++).

Also, there are a number of presets made from these primitives: